/*
 * Copyright 2009 SHOP.COM
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.shop.opensocial.mediated.types;

import java.util.Date;
import java.util.List;
import java.util.Map;

/**
 * Independent mediator for corresponding OpenSocial type
 *
 * @author Jordan Zimmerman
 */
public interface ActivityMediator
{
	/**
	 * Get a string specifying the application that this activity is associated with. Container
	 * support for this field is REQUIRED.
	 *
	 * @return A string specifying the application that this activity is associated with
	 */
	public String getAppId();

	/**
	 * Get a string specifying an optional expanded version of an activity. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return a string specifying an optional expanded version of an activity.
	 */
	public String getBody();

	/**
	 * Get a string specifying the body template message ID in the gadget spec. Container support for
	 * this field is OPTIONAL.
	 * <p/>
	 * Bodies may only have the following HTML tags: &lt;b&gt; &lt;i&gt;, &lt;a&gt;, &lt;span&gt;. The
	 * container may ignore this formatting when rendering the activity.
	 *
	 * @return a string specifying the body template message ID in the gadget spec.
	 */
	public String getBodyId();

	/**
	 * Get an optional string ID generated by the posting application. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return An optional string ID generated by the posting application.
	 */
	public String getExternalId();

	/**
	 * Get a string ID that is permanently associated with this activity. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return a string ID that is permanently associated with this activity.
	 */
	public String getId();

	/**
	 * Get the last updated date of the Activity, additional to the Opensocial specification for the
	 * REST-API. Container support for this field is OPTIONAL.
	 *
	 * @return the last updated date
	 */
	public Date getUpdated();

	/**
	 * Get any photos, videos, or images that should be associated with the activity.
	 * <p/>
	 * Container support for this field is OPTIONAL.
	 *
	 * @return A List of {@link MediaItemMediator} containing any photos, videos, or images that should be
	 *         associated with the activity.
	 */
	public List<MediaItemMediator> getMediaItems();

	/**
	 * Get the time at which this activity took place in milliseconds since the epoch. Container
	 * support for this field is OPTIONAL.
	 * <p/>
	 * Higher priority ones are higher in the list.
	 *
	 * @return The time at which this activity took place in milliseconds since the epoch
	 */
	public Long getPostedTime();

	/**
	 * Get the priority, a number between 0 and 1 representing the relative priority of this activity
	 * in relation to other activities from the same source. Container support for this field is
	 * OPTIONAL.
	 *
	 * @return a number between 0 and 1 representing the relative priority of this activity in
	 *         relation to other activities from the same source
	 */
	public Float getPriority();

	/**
	 * Get a string specifying the URL for the stream's favicon. Container support for this field is
	 * OPTIONAL.
	 *
	 * @return a string specifying the URL for the stream's favicon.
	 */
	public String getStreamFaviconUrl();

	/**
	 * Get a string specifying the stream's source URL. Container support for this field is OPTIONAL.
	 *
	 * @return a string specifying the stream's source URL.
	 */
	public String getStreamSourceUrl();

	/**
	 * Get a string specifing the title of the stream. Container support for this field is OPTIONAL.
	 *
	 * @return a string specifing the title of the stream.
	 */
	public String getStreamTitle();

	/**
	 * Get a string specifying the stream's URL. Container support for this field is OPTIONAL.
	 *
	 * @return a string specifying the stream's URL.
	 */
	public String getStreamUrl();

	/**
	 * Get a map of custom key/value pairs associated with this activity. Container support for this
	 * field is OPTIONAL.
	 *
	 * @return a map of custom key/value pairs associated with this activity.
	 */
	public Map<String, String> getTemplateParams();

	/**
	 * Get a string specifying the primary text of an activity. Container support for this field is
	 * REQUIRED.
	 * <p/>
	 * Titles may only have the following HTML tags: &lt;b&gt; &lt;i&gt;, &lt;a&gt;, &lt;span&gt;. The
	 * container may ignore this formatting when rendering the activity.
	 *
	 * @return astring specifying the primary text of an activity.
	 */
	public String getTitle();

	/**
	 * Get a string specifying the title template message ID in the gadget spec. Container support for
	 * this field is REQUIRED.
	 * <p/>
	 * The title is the primary text of an activity. Titles may only have the following HTML tags:
	 * <&lt;b&gt; &lt;i&gt;, &lt;a&gt;, &lt;span&gt;. The container may ignore this formatting when
	 * rendering the activity.
	 *
	 * @return a string specifying the title template message ID in the gadget spec.
	 */
	public String getTitleId();

	/**
	 * Get a string specifying the URL that represents this activity. Container support for this field
	 * is OPTIONAL.
	 *
	 * @return a string specifying the URL that represents this activity.
	 */
	public String getUrl();

	/**
	 * Get a string ID of the user who this activity is for. Container support for this field is
	 * OPTIONAL.
	 *
	 * @return a string ID of the user who this activity is for.
	 */
	public String getUserId();
}
